<HTML><HEAD><TITLE>number_merge(+Key, +Order, +List1, +List2, -List3)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Comparing and Sorting</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>number_merge(+Key, +Order, +List1, +List2, -List3)</H1>
Succeeds if List3 is a merged list of List1 and List2.  If both lists are
sorted, List3 will be sorted.  The sort is done according to the Key and
Order specifications.


<DL>
<DT><EM>Key</EM></DT>
<DD>A non-negative integer or a list of positive integers.
</DD>
<DT><EM>Order</EM></DT>
<DD>One of the atoms =&lt;, &gt;=, &lt; or &gt;.
</DD>
<DT><EM>List1</EM></DT>
<DD>List.
</DD>
<DT><EM>List2</EM></DT>
<DD>List.
</DD>
<DT><EM>List3</EM></DT>
<DD>List or variable.
</DD>
</DL>
<H2>Description</H2>
   Used to merge the sorted lists List1 and List2 to give the sorted list
   List3.

<P>
   If List1 and List2 are not lists of compound terms, use Key = 0.

<P>
   If List1 and List2 are lists of compound terms, then the sort will be
   according to the Keyth argument of the lists' elements. The Keyth
   argument of the list elements must be a numeric term.

<P>
   For two lists [e1,e2,e3] and [f1,f2,f3], e1 is compared to f1.  The
   resulting element (dictated by Key, Order and numerical ordering,
   with ties being resolved in favour of the element from List1)
   is put into List3, and the process continued with the remaining input
   lists.  This process continues until both lists are exhausted.

<P>
   In particular, this will merge two sorted lists into a sorted list.  The
   merge is stable, i.e. the order of elements with the same key is preserved.
   If List1 and List2 contains elements with identical keys, List1's elements
   will occur first in List3.

<P>
   In all cases where List1 and List2 are sorted, Order specifies whether
   the lists are sorted into ascending (&lt;, =&lt;) or descending (&gt;, &gt;=) order
   and whether duplicates are to be retained (=&lt;, &gt;=) or eliminated (&lt;, &gt;).
   The way to remember the Order argument is that it is the relation which
   holds between adjacent elements in the result.

<P>
   The sort is done according to numerical ordering of terms as opposed to
   merge/5 which uses the standard ordering of terms. See
   number_sort/4 for a discussion of the differences between numerical
   and standard ordering of numeric types.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>number_merge(+, +, +, +, -) is det
</UL>
<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>Key is greater than 0, and one of List1 and List2 does not    have all elements compound terms.
<DT><EM>(5) type error </EM>
<DD>Key is not an integer or a list of integers.
<DT><EM>(6) out of range </EM>
<DD>One of the compound terms in List1 or List2 has not got as    many as Key arguments.
</DL>
<H2>Examples</H2>
<PRE>
Success:
      number_merge(0,&lt;,[2,4,6],[1,3,5],L).
                      (gives L=[1,2,3,4,5,6]).
      number_merge(1,&gt;,[f(8),f(6)],[f(4),f(1)],L).
                      (gives L=[f(8),f(6),f(4),f(1)]).
      number_merge(2,&lt;,[f(2,1),f(6,4)],[f(6,3),f(8,6)],L).
                      (gives L=[f(2,1),f(6,3),f(6,4),f(8,6)]).
      number_merge(2,&lt;,[q(2,1),f(6,4)],[a(6,3),i(8,6)],L).
                      (gives L=[q(2,1),a(6,3),f(6,4),i(8,6)]).
      number_merge(0,=&lt;,[1,2],[3,4,4,5],L).
                      (gives L=[1,2,3,4,4,5]).
      number_merge([2,1], =&lt;, [f(1,a(1)), f(0,a(3))], [f(3,a(2)), f(1,a(4))], L).
                      (gives L=[f(1,a(1)), f(3,a(2)), f(0,a(3)), f(1,a(4))]).
Fail:
      number_merge(0,&lt;,[2,4,6],[1,3,5],[1,2,3,4,5]).
Error:
      number_merge(0,&gt;,[1],[Q,2],L).                  (Error 4).
      number_merge(1,&lt;,[f(1,2),f],[f(3,4),h(1,2)],L). (Error 5).
      number_merge(0.0,&lt;,[f(1)],[f(2)],L).            (Error 5).
      number_merge(0,&lt;,[f(1),f(7)],[f(8),f(10)],L).   (Error 5).
      number_merge(0,&gt;,[1,e,q],[2],L).                (Error 5).
      number_merge(2,&lt;,[f(1,2)],[f(8)],L).            (Error 6).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/termcomp/merge-3.html">merge / 3</A>, <A HREF="../../kernel/termcomp/merge-5.html">merge / 5</A>, <A HREF="../../kernel/termcomp/number_merge-3.html">number_merge / 3</A>
</BODY></HTML>
